home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Aminet 52
/
Aminet 52 (2002)(GTI - Schatztruhe)[!][Dec 2002].iso
/
Aminet
/
dev
/
gg
/
gengetopt-2.6.lha
/
gengetopt-2.6
/
README
< prev
next >
Wrap
Text File
|
2002-03-02
|
21KB
|
572 lines
GNU Gengetopt 2.6
March 2nd, 2002
This program generates a C function that uses getopt_long function to parse
the command line options, to validate them and fills a struct.
Thus your program can now handle options such as:
myprog --input foo.c -o foo.o --no-tabs -i 100 *.class
And both long options (those that start with --) and short options (start
with - and consist of only one character) can be handled. For standards
about short and long options you may want to take a look at the GNU Coding
Standards.
gengetopt is free software. Please see the file LICENSE and COPYING for
details.
Notice that: Use of gengetopt does not impose any particular license on the
generated code: the code generated is not under any license.
For documentation, please read this file.
gengetopt is perfect if you are too lazy (like me) to write all stuff
required to call getopt_long, and when you have a
program and wish it took options.
Generated code works if you use GNU Autoconf or GNU Automake.
Gengetopt has originally been written by Roberto Arturo Tena Sanchez
<arturo@directmail.org>, and currently maintained by Lorenzo Bettini
<bettini@gnu.org>.
Gengetopt is a GNU program and its main home page is at GNU site:
http://www.gnu.org/software/gengetopt/gengetopt.html,
Download
You can download it from GNU's ftp site:
ftp://ftp.gnu.org/gnu/gengetopt/ or from one of its mirrors (see
http://www.gnu.org/prep/ftp.html).
I do not distribute Windows binaries anymore; since, they can be easily
built by using Cygnus C/C++ compiler, available at http://www.cygnus.com/.
However, if you don't feel like downloading such compiler, you can request
such binaries directly to me, by e-mail (bettini@gnu.org) and I can send
them to you.
You may also want to check the md5sum of the archives, which are also
digitally signed by me (Lorenzo Bettini) with GNU gpg
(http://www.gnupg.org). My GPG public key can be found at my home page (see
at the end of this doc).
You can also get the patches, if they are available for a particular release
(see below for patching from a previous version).
Changes in this release
* fixed documentation (thanks to Francesco Potorti <pot@gnu.org>)
* function names and names used in #ifndef directives in generated
sources are canonized, thus avoiding errors by the compiler (notified
by Francesco Potorti and Alexey Mahotkin <alexm@hsys.msk.ru>)
* fixed line number when reporting an error in a .ggo file, and '\n' is
no longer needed at the end of a .ggo file (notified by Francesco
Potorti)
* in the generated parser use HAVE_STRDUP to check whether the standard
strdup function can be used, and use EXIT_SUCCESS and EXIT_FAILURE for
exit (suggested by Frans E. van Dorsselaer <frans@biabv.com>)
* do not exit with error if an empty desc for an option is given (thanks
to Excoffier Denis <Denis.Excoffier@eurocopter.com>)
* fixed a bug in creation of string for the comment header in the
generated sources (thanks to Xavier Trochu <xtrochu@yahoo.com>)
* Added default values in options for integer and string options (with
help of Ralf Zeise <Zeise@serving-gmbh.de>)
Changes in release 2.5
* much more recent versions of getopt.h, getopt.c, getopt1.c are provided
(the previous ones were very very old!), that do not rely on alloca
anymore.
* when a flag option is given the corresponding _given variable is set
(bug fixed by Guillaume Chazarain <booh@altern.org>).
* Fixed documentation of sample1, as suggested by Lutz Maibaum
<lutz@gold.cchem.berkeley.edu>.
* Avoid a warning due to generated gengetopt_strdup (thanks to Brian
Minard <bminard@flatfoot.ca>)
* the generated print_help function use a different printf for every
option, thus avoiding a single printf with a possible very huge string
(thanks to Herbert Thoma <tma@iis.fhg.de>)
see also NEWS file and ChangeLog for the complete list of changes between
versions (also summarized in old_changes.html).
Installation
See the file INSTALL for detailed building and installation instructions;
anyway if you're used to compiling Linux software that comes with sources
you may simply follow the usual procedure:
cd <source code main directory>
./configure
make
make install
Note: unless you specify a different install directory by --prefix option of
configure (e.g. ./configure --prefix=<your home>), you must be root to 'make
install'.
You can also run some tests by issuing 'make check'.
Files will be installed in the following directories:
* Executables -> /prefix/bin
* Docs -> /prefix/share/doc/gengetopt
* Man pages -> /prefix/man
* Examples -> /prefix/share/doc/gengetopt/examples
* Util files -> /prefix/share/gengetopt
Default value for prefix is /usr/local but you may change it with --prefix
option to configure (see above).
What you need to build gengetopt
Actually you need nothing more than a Unix C/C++ compiler.
getopt_long function is usually in the standard C library, but there may be
some C libraries which don't include it; in this case you have to link the
program that uses the file generated by gengetopt with the files getopt.c
and getopt1.c and include getopt.h in your project. You may also need to
link alloca.c.We obviously provide these files in the utility files
directory (/prefix/share/gengetopt). These files are part of the GNU C
library. You may want to take a look at getopt man page. Read also
no_getopt_long.txt. for instuctions on how to check if getopt_long and
alloca are part of the library and how to deal with their lacking (using
autoconf and automake).
gengetopt has been developed under Linux, using gcc, and bison (yacc) and
flex (lex), and ported under Windows with Cygnus C/C++ compiler, available
at http://www.cygnus.com/. I used the excellent GNU Autoconf and Automake. I
also used Autotools (ftp://ftp.ugcs.caltech.edu/pub/elef/autotools) which
creates a starting source tree (according to GNU standards) with autoconf,
automake starting files, and getopt_long (for command line parsing).
Actually, unless you want to develop gengetopt, you don't need all these
tools to build gengetopt because I provide generated sources; you don't need
neither bison (yacc) nor flex (lex), for the same reason. Actually programs
that use lex generated files need to link with library libfl (or libl for
lex); anyway configuration phase can discover if this library is missing and
in that case it sets the program to link with a source file I provide. This
hack works for flex: I don't know about lex generated scanners. But, again,
this is a problem only if you develop gengetopt and you use lex.
Patching from a previous version
If you downloaded a patch, say gengetopt-1.3-1.3.1-patch.gz (i.e. the patch
to go from version 1.3 to version 1.3.1), cd to the directory with sources
from the previous version (gengetopt-1.3) and type:
gunzip -cd ../gengetopt-1.3-1.3.1.patch.gz | patch -p1
and restart the compilation process (if you had already run configure a
simple make will do).
Usage (a little tutorial)
The command line options, which have to be handled by gengetopt generated
function, are specified in a file (typically with .ggo extension). This file
consist in lines of sentences with the following formats:
package <packname>
version <version>
option <long> <short> <desc> <argtype> {default="<default value>"} <required>
option <long> <short> <desc> flag <onoff>
option <long> <short> <desc> no
Where:
packname
Double quoted string.
version
Double quoted string.
purpose
What the program does (even on more than one line), it will be
printed with the help. Double quoted string.
long
The long option, a double quoted string with upper and lower
case chars, digits, '-' and '.'. No spaces allowed. The name
of the variables generated to store arguments are long options
converted to be legal C variable names. This means, '.' and '-'
are both replaced by '_'. '_arg' is appended, or '_flag' for a
flag.
short
The short option, a single upper or lower case char, or a
digit. If a '-' is specified, then no short option is considered
for the long option (thus long options with no associated short
options are allowed).
desc
Double quoted string with upper and lower case chars, digits,
'-', '.' and spaces. First character must not be a space.
argtype
string, int, short, long, float, double, longdouble or longlong.
default
an optional default value for the option. The value must always
be specified as a double quoted string.
required
yes or no.
onoff
on or off. This is the state of the flag when the program starts.
If user specifies the option, the flag toggles.
The third type of option is used when the option does not take any argument.
It must not be required.
Comments begins with '#' in any place of the line and ends in the end of
line.
Here's an example of such a file (the file is called sample1.ggo)
# file sample1.ggo
option "str-opt" s "A string option" string no
option "my-opt" m "Another integer option" int no
option "int-opt" i "A int option" int yes
option "flag-opt" - "A flag option" flag off
option "funct-opt" F "A function option" no
option "long-opt" - "A long option" long no
option "def-opt" - "A string option with default" string
default="Hello" no
The simplest way to use gengetopt is to pass this file as the standard
input, i.e.:
gengetopt < sample1.ggo
by default gengetopt generates cmdline.h and cmdline.c. Otherwise we can
specify these names with a command line option:
gengetopt < sample1.ggo --file-name=cmdline1 --unamed-opts
The option --unamed-opts allows the generated command line parser to accept
also names, without an option (for instance you can pass a file name without
an option in front of it, and also use wildcards, such as *.c, foo*.? and so
on).
In cmdline1.h you'll find the generated C struct:
/* cmdline1.h */
/* File autogenerated by gengetopt version 2.6 */
#ifndef _cmdline1_h
#define _cmdline1_h
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/* Don't define PACKAGE and VERSION if we use automake. */
#if defined PACKAGE
# undef PACKAGE
#endif
#define PACKAGE "sample1"
#if defined VERSION
# undef VERSION
#endif
#define VERSION "2.0"
struct gengetopt_args_info {
char * str_opt_arg; /* A string option. */
int my_opt_arg; /* Another integer option. */
int int_opt_arg; /* A int option. */
int flag_opt_flag; /* A flag option (default=off). */
long long_opt_arg; /* A long option. */
char * def_opt_arg; /* A string option with default (default='Hello'). */
int help_given ; /* Whether help was given. */
int version_given ; /* Whether version was given. */
int str_opt_given ; /* Whether str-opt was given. */
int my_opt_given ; /* Whether my-opt was given. */
int int_opt_given ; /* Whether int-opt was given. */
int flag_opt_given ; /* Whether flag-opt was given. */
int funct_opt_given ; /* Whether funct-opt was given. */
int long_opt_given ; /* Whether long-opt was given. */
int def_opt_given ; /* Whether def-opt was given. */
char **inputs ; /* unamed options */
unsigned inputs_num ; /* unamed options number */
} ;
int cmdline_parser (int argc, char * const *argv, struct gengetopt_args_info *args_info);
void cmdline_parser_print_help(void);
void cmdline_parser_print_version(void);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* _cmdline1_h */
Notice that by default the generated function is called cmdline_parser (see
the command line options below, to override this name), and it takes the
arguments that main receives and a pointer to such a struct, that it will be
filled.
And here's how this function can be used inside the main program:
/* main1.cc */
/* we try to use gengetopt generated file in a C++ program */
/* we don't use autoconf and automake vars */
#include <iostream.h>
#include "stdlib.h"
#include "cmdline1.h"
int
main (int argc, char **argv)
{
gengetopt_args_info args_info;
cout << "This one is from a C++ program" << endl ;
cout << "Try to launch me with some options" << endl ;
cout << "(type sample1 --help for the complete list)" << endl ;
cout << "For example: ./sample1 *.* --funct-opt" << endl ;
/* let's call our cmdline parser */
if (cmdline_parser (argc, argv, &args_info) != 0)
exit(1) ;
cout << "Here are the options you passed..." << endl;
for ( unsigned i = 0 ; i < args_info.inputs_num ; ++i )
cout << "file: " << args_info.inputs[i] << endl ;
if ( args_info.funct_opt_given )
cout << "You chose --funct-opt or -F." << endl ;
if ( args_info.str_opt_given )
cout << "You inserted " << args_info.str_opt_arg << " for " <<
"--str-opt option." << endl ;
if ( args_info.int_opt_given )
cout << "This is the integer you input: " <<
args_info.int_opt_arg << "." << endl;
if (args_info.flag_opt_given)
cout << "The flag option was given!" << endl;
cout << "The flag is " << ( args_info.flag_opt_flag ? "on" : "off" ) <<
"." << endl ;
cout << args_info.def_opt_arg << "! ";
cout << "Have a nice day! :-)" << endl ;
return 0;
}
Now you can compile main1.cc and the cmdline1.c generated by gengetopt and
link all together to obtain sample1 executable:
gcc -c cmdline1.c
g++ -c main1.cc
g++ -o sample1 cmdline1.o main1.o
(Here we assume that getopt_long is included in the standard C library; see
'What you need to build gengetopt' section).
Now let's try some tests with this program:
$ ./sample1 -s "hello" --int-opt 1234
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Here are the options you passed...
You inserted hello for --str-opt option.
This is the integer you input: 1234.
The flag is off.
Have a nice day! :-)
You can also pass many file names to the command line (this also shows how
flags work):
$ ./sample1 *.h -i -100 -x
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
Here are the options you passed...
file: cmdline1.h
file: cmdline2.h
file: cmdline.h
file: getopt.h
This is the integer you input: -100.
The flag is on.
Have a nice day! :-)
And if we try to omit the --int-opt (or -i), which is required, we get an
error:
$ ./sample1
This one is from a C++ program
Try to launch me with some options
(type sample1 --help for the complete list)
For example: ./sample1 *.* --funct-opt
sample1: `--int-opt' (`-i') option required!
If you're curious you may want to take a look at the generated C file.
You may find other examples in /prefix/share/doc/gengetopt.
Warning for Windows users
If you run Windows, please remember that DOS shell does not translate
wildcards, and thus the previous test which uses '*.h' will not work.
Options
This is the output of gengetopt --help:
$ gengetopt --help
gengetopt 2.6
Purpose:
This program generates a C function that uses getopt_long function
to parse the command line options, validate them and fill a struct.
Usage: gengetopt [OPTIONS]...
-h --help Print help and exit
-V --version Print version and exit
-iSTRING --input=STRING input file (default std input)
-fSTRING --func-name=STRING name of generated function (default='cmdline_parser')
-FSTRING --file-name=STRING name of generated file (default='cmdline')
-l --long-help long usage line in help
-u --unamed-opts accept filenames
--no-handle-help do not handle --help|-h automatically
--no-handle-version do not handle --version|-V automatically
--no-handle-error do not exit on errors
Maintained by Lorenzo Bettini <bettini@gnu.org>
Report bugs to <bug-gengetopt@gnu.org>
The options should be clear; in particular:
* if no --func-name is given, cmdline_parser is taken by default;
* with --long-help option, the "Usage" line reports all the options; this
may be unpleasant if options are many;
* with --unamed-opts we can accept also options without a name, which, in
most case, means that we can pass many file names to the program (see
the example above when we call sample1 *.h).
* if --no-handle-help (--no-handle-version) is given the command line
--help|-h (--version|-V) is not handled automatically, so the
programmer will be able to print some other information; then the
function for printing the standard help (version) response can be used;
this function is called <parser-name>_print_help
(<parser-name>_print_version), where <parser-name> is the name
specified with ---func-name or the default cmdline_parser.
* if --no-handle-error is given, an error in the parsing does not provoke
the exit of the program; instead, since the parser function, in case of
an error, returns non 0, the program can print a help message, as
gengetopt itself does in case of an error (try it!).
You may have already guessed it: gengetopt uses gengetopt itself for command
line options, and this is its specification file:
purpose "This program generates a C function that uses getopt_long function
to parse the command line options, validate them and fill a struct."
option "input" i "input file. default std input" string no
option "func-name" f "name of generated function" string default="cmdline_parser" no
option "file-name" F "name of generated file" string default="cmdline" no
option "long-help" l "long usage line in help" no
option "unamed-opts" u "accept filenames" no
option "no-handle-help" - "do not handle --help|-h automatically" no
option "no-handle-version" - "do not handle --version|-V automatically" no
option "no-handle-error" - "do not exit on errors" no
In particular the command line for gengetopt itself is generated with the
following command:
gengetopt --input=cmdline.ggo --no-handle-version --no-handle-help --no-handle-error
Indeed when --help|-h is passed on the command line, gengetopt will call
cmdline_parser_print_help() and then the lines for reporting bugs. When
--version|-V is passed, it will call cmdline_parser_print_version() and then
prints a copyright.
If an error occurs it prints a message on the screen:
$ ./gengetopt --zzzz
./gengetopt: unrecognized option `--zzzz'
Run gengetopt --help to see the list of options.
Credits
See THANKS file :-)
Feedback
Tell us if you like this software :-)
Actually we want to extend it, so if you have some ideas... The most import
one will be to make gengetopt more customizable :-)
Please send all bug reports by electronic mail to:
bug-gengetopt@gnu.org
Mailing Lists
The following mailing lists are available:
* help-gengetopt@gnu.org, for generic discussions about the program and
for asking for help about it (open mailing list),
http://mail.gnu.org/mailman/listinfo/help-gengetopt
* info-gengetopt@gnu.org, for receiving information about new releases
and features (read-only mailing list),
http://mail.gnu.org/mailman/listinfo/info-gengetopt
if you want to subscribe to a mailing list just go to the URL and follow the
instructions.
Lorenzo Bettini Roberto Arturo Tena Sanchez
http://w3.newnet.it/bettini or http://arturo.directmail.org
http://infostud.dsi.unifi.it/~bettini<arturo@directmail.org>,
(very fast if you're in University)
<bettini@gnu.org>.
gengetopt is free software. See the file LICENSE and COPYING for copying
conditions. Anyway we won't get offended if you send us a postcard :-)
C/C++ files are formatted with GNU Source-highlight
(http://www.gnu.org/software/src-highlite/) by Lorenzo Bettini.
------------------------------------------------------------------------
Return to GNU's home page.
Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also
other ways to contact the FSF.
Please send comments on these web pages to webmasters@gnu.org, send other
questions to gnu@gnu.org.
Copyright (C) 2001 Free Software Foundation, Inc., 59 Temple Place - Suite
330, Boston, MA 02111, USA
Verbatim copying and distribution of this entire article is permitted in any
medium, provided this notice is preserved.
Updated:9 Jan 2001 mhw
------------------------------------------------------------------------